DWSTRING Class

The DWSTRING class implements a dynamic unicode null terminated string. Free Basic has a dynamic string data type (STRING). a fixed-length ansi data type (ZSTRING) and a fixed-length unicode data type (WSTRING), but it lacks a dynamic unicode string. DWSTRING behaves as if it was a native data type, working transparently with all of the intrinsic Free Basic string functions and operators (consult the FreeBasic documentation for a list of them and how they work). One important diference is that VARPTR and the @ operator don’t return the address of the buffer, but the address of the class. To get the address of the buffer use STRPTR or the * operator.

Include file: AfxNova/DWSTRING.inc.

Constructors

CONSTRUCTOR
CONSTRUCTOR (BYREF wszStr AS CONST WSTRING)
CONSTRUCTOR (BYVAL pwszStr AS WSTRING PTR)
CONSTRUCTOR (BYREF ansiStr AS STRING, BYVAL nCodePage AS UINT = 0)
CONSTRUCTOR (BYREF dws AS DWSTRING)
CONSTRUCTOR (BYREF bs AS BSTRING)
CONSTRUCTOR (BYVAL nChars AS LONG, BYREF wszFill AS CONST WSTRING)
CONSTRUCTOR (BYVAL n AS LONGINT)
CONSTRUCTOR (BYVAL n AS DOUBLE)

1. Creates an empty Unicode string buffer with an initial null-terminated string.

Example: DIM dws AS DWSTRING

2. Initializes a DWSTRING instance from a wide string pointer.

DIM wsz AS WSTRING * 30 = "This is a test string"
DIM dwsText AS DWSTRING = wsz

3. Initializes a DWSTRING from an ANSI or UTF-8 encoded string, with optional code page support.

Example: DIM s AS STRING = "Hello, world"
         DIM dws AS DWSTRING = s
Example: DIM dws AS DWSTRING = DWSTRING("Hello, utf", CP_UTF8)

For a list of code pages see: Code Page Identifiers

5. Creates a copy of an existing DWSTRING.

Example: DIM dws1 AS DWSTRING = "Test string"
         DIM dws2 AS DWSTRING = dws1

6. Creates a DWSTRING with a fixed-length buffer, initialized with a fill character.

Example: DIM dws AS DWSTRING = DWSTRING(260, " ")

7. Initializes a DWSTRING with a numeric value, allowing automatic conversion.

Example: DIM dwsNum AS DWSTRING = 12345
Example: DIM dwsFloat AS DWSTRING = 3.1415

Remarks

DWSTRING works transparently with literals and Free Basic native strings, e.g.

DIM dws AS DWSTRING = "One"
DIM s AS STRING = "Three"
dws = dws & " Two " & s
PRINT dws

It can be used with Windows API functions, e.g.

DIM nLen AS LONG = SendMessageW(hwnd, WM_GETTEXTLENGTH, 0, 0)
DIM dwsText AS DWSTRING = WSPACE(nLen + 1)
SendMessageW(hwnd, WM_GETTEXT, nLen + 1, cast(LPARAM, *cwsText))
dwsText = LEFT(dwsText, LEN(dwsText) - 1)
PRINT dwsText

We can use arrays of DWSTRING strings transparently, e.g.

DIM rg(1 TO 10) AS DWSTRING
FOR i AS LONG = 1 TO 10
   rg(i) = "string " & i
NEXT
FOR i AS LONG = 1 TO 10
   PRINT rg(i)
NEXT

A two-dimensional array

DIM rg2 (1 TO 2, 1 TO 2) AS DWSTRING
rg2(1, 1) = "string 1 1"
rg2(1, 2) = "string 1 2"
rg2(2, 1) = "string 2 1"
rg2(2, 2) = "string 2 2"
PRINT rg2(2, 1)

REDIM PRESERVE / ERASE

REDIM rg(0) AS DWSTRING
rg(0) = "string 0"
REDIM PRESERVE rg(0 TO 2) AS DWSTRING
rg(1) = "string 1"
rg(2) = "string 2"
PRINT rg(0)
PRINT rg(1)
PRINT rg(2)
ERASE rg

You can also use it with files:

Using FreeBasic intrinsic statements:

DIM dws AS DWSTRING = "Дмитрий Дмитриевич Шостакович"
DIM f AS LONG = FREEFILE
OPEN "Test.txt" FOR OUTPUT ENCODING "utf16" AS #f
PRINT #f, dws
CLOSE #f

Using the Windows API:

' // Writing to a file
DIM dwsFilename AS DWSTRING = "тест.txt"
DIM dwsText AS DWSTRING = "Дмитрий Дмитриевич Шостакович"
DIM hFile AS HANDLE = CreateFileW(dwsFilename, GENERIC_WRITE, 0, NULL, CREATE_ALWAYS, FILE_ATTRIBUTE_NORMAL, NULL)
IF hFile THEN
   DIM dwBytesWritten AS DWORD
   DIM bSuccess AS LONG = WriteFile(hFile, dwsText, LEN(dwsText) * 2, @dwBytesWritten, NULL)
   CloseHandle(hFile)
END IF

' // Read the file
hFile = CreateFileW(dwsFilename, GENERIC_READ, FILE_SHARE_READ, NULL, OPEN_EXISTING, FILE_FLAG_SEQUENTIAL_SCAN, NULL)
IF hFile THEN
   DIM dwFileSize AS DWORD = GetFileSize(hFile, NULL)
   IF dwFileSize THEN
      DIM dwsOut AS DWSTRING = WSPACE(dwFileSize \ 2)
      DIM bSuccess AS LONG = ReadFile(hFile, *dwsOut, dwFileSize, NULL, NULL)
      CloseHandle(hFile)
      PRINT dwsOut
   END IF
END IF

Notice that, contrarily to CreateFileW, FreeBasic’s OPEN statement doesn’t allow to use unicode for the file name.

Operators

Operator *

Dereferences the DWSTRING.
One * returns the address of the DWSTRING buffer.
Two ** returns the address of the start of the string data.

OPERATOR * (BYREF dws AS DWSTRING) AS WSTRING PTR

Casting and Conversions

Operator Cast

OPERATOR CAST () BYREF AS CONST WSTRING
OPERATOR CAST () AS ANY PTR

Returns a pointer to the DWSTRING buffer or the string data. These operators aren’t called directly.

bstr

Returns the contents of the DWSTRING as a BSTR.

FUNCTION bstr () AS BSTR

OEM

Converts from Unicode to OEM code page and from OEM to Unicode.

PROPERTY OEM () AS STRING
PROPERTY OEM (BYREF OEMString AS STRING)

Utf8

Converts from UTF8 to Unicode and from Unicode to UTF8.

PROPERTY Utf8() AS STRING
PROPERTY Utf8 (BYREF utf8String AS STRING)

vptr

Returns the address of the string buffer.

FUNCTION vptr () AS WSTRING PTR

wchar

Returns the string data as a new unicode string allocated with CoTaskMemAlloc.

FUNCTION wchar () AS WSTRING PTR

Useful when we need to pass a pointer to a null terminated wide string to a function or method that will release it. If we pass a WSTRING it will GPF. If the length of the input string is 0, CoTaskMemAlloc allocates a zero-length item and returns a valid pointer to that item. If there is insufficient memory available, CoTaskMemAlloc returns NULL.

Methods

Capacity

Gets/sets the size of the internal buffer. The size is the number of bytes which can be stored without further expansion.

PROPERTY Capacity() AS UINT
PROPERTY Capacity (BYVAL nValue AS LONG)

ChrW

Returns a wide-character string from a codepoint. If the codepoint is higher than 65535, the value returned a surrogate pair.

FUNCTION ChrW (BYVAL codePoint AS UInteger) AS DWSTRING